Skip to content

Add Ruby SDK support#41

Merged
donald-pinckney merged 25 commits into
mainfrom
add-ruby-support
May 28, 2026
Merged

Add Ruby SDK support#41
donald-pinckney merged 25 commits into
mainfrom
add-ruby-support

Conversation

@donald-pinckney

Copy link
Copy Markdown
Collaborator

Summary

  • Add 11 Ruby reference files (~2100 lines) covering all major Temporal SDK features: workflows, activities, signals/queries/updates, child workflows, versioning, testing, error handling, data conversion, observability, determinism protection, and advanced features
  • Update SKILL.md to include Ruby in description, overview, and getting started guide
  • Add Ruby entry to core/determinism.md SDK Protection Mechanisms section

Details

The Ruby SDK (temporalio gem, GA) uses a fundamentally different determinism approach from Python (sandbox) and TypeScript (V8 isolate):

  • Illegal Call Tracing via Ruby's TracePoint to detect forbidden method calls at runtime
  • Durable Fiber Scheduler to make fiber operations deterministic

Ruby-specific sections added that don't exist in Python/TypeScript:

  • Cancellation (Token-based) — uses Temporalio::Cancellation objects
  • ActiveModel Integration — Ruby equivalent of Pydantic
  • Converter Hints — workflow_arg_hint/workflow_result_hint for type guidance
  • Illegal Call Tracing Gotchas — third-party gems triggering NondeterminismError
  • Activity Concurrency and Executors — ThreadPool configuration
  • Rails Integration — ActiveRecord, Zeitwerk, forking considerations

Test plan

  • Verify Ruby reference files are loaded correctly by the skill
  • Test with a sample Ruby Temporal project to validate code examples
  • Review alignment with Python/TypeScript content structure

🤖 Generated with Claude Code

donald-pinckney and others added 4 commits March 16, 2026 18:23
Created complete Ruby reference documentation covering:
- ruby.md: Overview, quick start, key concepts, file organization
- patterns.md: Signals, queries, updates, child workflows, saga, cancellation, etc.
- determinism.md: Illegal call tracing, safe alternatives table
- determinism-protection.md: TracePoint, durable fiber scheduler, customization
- versioning.md: Patching API, type versioning, worker versioning
- testing.md: WorkflowEnvironment, mocking, replay, activity testing
- error-handling.md: ApplicationError, retries, timeouts, workflow failure
- data-handling.md: Data converter, ActiveModel, hints, search attributes
- observability.md: Logging, metrics, best practices
- gotchas.md: Common mistakes, illegal call tracing issues
- advanced-features.md: Schedules, async completion, worker tuning, Rails

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Self-review fixes:
- patterns.md: Remove non-existent `workflow_run` annotation; entry point
  is `def execute` (no annotation needed, unlike Python's @workflow.run)
- patterns.md: Remove conflicting manual query methods that duplicated
  workflow_query_attr_reader
- error-handling.md: Remove `await` keyword (doesn't exist in Ruby)
- gotchas.md: Replace TS-style CancellationScope with Ruby's
  Temporalio::Cancellation token-based detached cancellation
- data-handling.md: Replace homemade ActiveModel mixin with official SDK
  pattern using ActiveSupport::Concern + ActiveModel::Serializers::JSON
- data-handling.md: Fix list_workflows call signature (positional, not kw)
- ruby.md, gotchas.md: Fix require paths to use 'temporalio/activity'
  instead of 'temporalio/activity/definition'

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- patterns.md: Fix external workflow signal to use class method ref
  (TargetWorkflow.data_ready instead of TargetWorkflow, :data_ready)
- patterns.md: Add ? suffix to all_handlers_finished (Ruby boolean convention)
- ruby.md: Add 'default' namespace to Client.connect calls

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- SKILL.md: Add "Temporal Ruby" trigger phrase to description
- SKILL.md: Update Overview to list Ruby as supported language
- SKILL.md: Add Ruby entry to Getting Started guide
- core/determinism.md: Add Ruby SDK Protection Mechanism entry
  (Illegal Call Tracing via TracePoint + Durable Fiber Scheduler)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@jb08

jb08 commented Mar 27, 2026

Copy link
Copy Markdown

Thank you for doing this! As a ruby sdk user, very interested in this MR. Any update on ETA?

@hughevans

Copy link
Copy Markdown

Looks good!

@donald-pinckney donald-pinckney changed the base branch from dev to main April 17, 2026 19:07
@chadxz

chadxz commented May 7, 2026

Copy link
Copy Markdown

Yes please

@chris-olszewski chris-olszewski left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall looks good. Just a few suggestions

Comment thread references/ruby/ruby.md Outdated
Comment thread references/ruby/gotchas.md
Comment thread references/ruby/testing.md
Comment thread references/ruby/patterns.md Outdated
Comment thread references/ruby/observability.md
Comment thread references/ruby/determinism-protection.md Outdated
Comment thread references/ruby/determinism-protection.md

@bdewater-thatch bdewater-thatch left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Saw this mentioned on the Slack. Long time Ruby/Rails user, still a bit new to Temporal, so reviewing through that lens :)

Comment thread references/ruby/advanced-features.md Outdated
Comment thread references/ruby/advanced-features.md
Comment thread references/ruby/gotchas.md Outdated
Comment thread references/ruby/gotchas.md Outdated
donald-pinckney and others added 2 commits May 26, 2026 14:13
Co-authored-by: Bart de Water <118401830+bdewater-thatch@users.noreply.github.com>
Co-authored-by: Chris Olszewski <chrisdolszewski@gmail.com>
Comment thread references/ruby/gotchas.md Outdated
Co-authored-by: Bart de Water <118401830+bdewater-thatch@users.noreply.github.com>
Co-authored-by: Donald Pinckney <donald_pinckney@icloud.com>
Comment thread references/ruby/advanced-features.md Outdated
Comment thread references/ruby/advanced-features.md Outdated
donald-pinckney and others added 13 commits May 26, 2026 18:57
Co-authored-by: Chris Olszewski <chrisdolszewski@gmail.com>
Document the workflow_init class method (Ruby's equivalent of Python's
@workflow.init) for initializing workflow state before signal/update
handlers run. Parallels the Python reference's Workflow Init section.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the graceful_shutdown_period worker option (Ruby's equivalent of
Python's graceful_shutdown_timeout) to the Worker Tuning section, with
an explanation of the worker shutdown sequence.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the Handling Activity Errors example to re-raise when
Temporalio::Error.canceled? is true (Ruby's equivalent of Python's
is_cancelled_exception), so a canceled activity cancels the workflow
rather than failing it. Also clarify that only ApplicationError fails a
workflow; other exceptions only fail/retry the workflow task.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the workflow_failure_exception_type / worker-option examples
(misaligned with Python and already covered in advanced-features.md)
with Python's example of raising an ApplicationError to deliberately
fail a workflow. Add the terse note about not using non_retryable
inside a workflow.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document configuring the logger via Client.connect (logger: kwarg),
which is used by both Temporalio::Workflow.logger and the activity
logger. Parallels Python's Customizing Logger Configuration section.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Run saga compensations with a detached Temporalio::Cancellation so they
still execute when the workflow is canceled mid-saga. Previously they
used the workflow cancellation, which is already canceled at that point,
so the compensation activities would be canceled before starting. This
is the Ruby equivalent of Python's asyncio.shield.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Note that Temporalio::Workflow.patched memoizes per patch ID, so it
can't be used reliably in loops; append a sequence number to the patch
ID per iteration. This behavior is shared with Python and .NET.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
donald-pinckney and others added 3 commits May 28, 2026 17:29
Document configuring default_versioning_behavior on
Temporalio::Worker::DeploymentOptions, paralleling Python's Worker
Configuration with Default Behavior section.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Configuring Workers for Versioning example used class/kwarg names
that don't exist in the SDK. Correct them to deployment_options:,
Temporalio::Worker::DeploymentOptions, and
Temporalio::WorkerDeploymentVersion, matching the actual API and the
Worker Configuration with Default Behavior example.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
max_concurrent_workflow_tasks and max_concurrent_activities are not
valid Worker.new kwargs. Use the tuner: option with
Temporalio::Worker::Tuner.create_fixed(workflow_slots:, activity_slots:)
to control concurrent execution slots.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@donald-pinckney donald-pinckney marked this pull request as ready for review May 28, 2026 21:41
@donald-pinckney donald-pinckney requested a review from a team as a code owner May 28, 2026 21:41
donald-pinckney and others added 2 commits May 28, 2026 17:48
Rename the section to 'Workflow Init Decorator' to match the Python
reference's heading.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Split the flat Metrics section into 'Enabling SDK Metrics' and
'Key SDK Metrics' subsections, matching the Python reference.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants